From The Blog

Run GitHub Actions on Subdirectories

I come across a lot of “greedy” GitHub Actions, where automation is running across a whole project instead of only on the parts that are relevant. Examples might be code linters that report problems with documentation folders, or the inverse of that. It’s especially problematic in monorepos where we probably want to use the same tool when we’re doing the same task for different subfolders, but that tool might not make sense to run everywhere. Continue reading

OpenAPI Overlays to avoid API oversharing

Most APIs aren’t perfect. By design they are long-lived and may serve many audiences. I see a lot of organisations maintaining multiple versions of APIs, or simply not documenting some of the endpoints to avoid them being included in the published documentation and confusing users. The problem of API redaction is a real one in most organisations, and it goes unsolved or is solved in a way that causes ongoing friction. I’ve helped a few API projects to solve this problem with the new OpenAPI Overlay specification so I thought I’d share! Continue reading

Use multi-line values in GitHub Actions

I created an action that needed a rich Markdown value in it, because it’s our weekly meeting agenda template which is formatted for humans with links and paragraphs and things. The Action syntax produced errors when trying to add the content directly to the action, but I got it to work by putting the content into the file, and using the file contents as an environment variable. That’s really the punchline of this post, but read on if you would like more details and some examples. Continue reading

Talks, Articles, Podcasts, and More

Article

API Evangelist Conversation: Overlays


API Evangelist Conversation, December 2024
Video

API Evangelist Conversation: Redocly CLI


API Evangelist Conversation, October 2024
Slides

DevOps Your Docs


WriteTheDocs Atlantic, September 2024
Slides

API Description Pipelines


APIDays London, September 2024
Slides

AsyncAPI governance the easy way


APIDays London, September 2024